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Abstract 


This document describes a file format suitable for describing 
directory information or modifications made to directory information. 
The file format, known as LDIF, for LDAP Data Interchange Format, is 
typically used to import and export directory information between 
LDAP-based directory servers, or to describe a set of changes which 
are to be applied to a directory. 


Background and Intended Usage 


There are a number of situations where a common interchange format is 
desirable. For example, one might wish to export a copy of the 
contents of a directory server to a file, move that file to a 
different machine, and import the contents into a second directory 
server. 


Additionally, by using a well-defined interchange format, development 
of data import tools from legacy systems is facilitated. A fairly 
simple set of tools written in awk or perl can, for example, convert 
a database of personnel information into an LDIF file. This file can 
then be imported into a directory server, regardless of the internal 
database representation the target directory server uses. 


The LDIF format was originally developed and used in the University 
of Michigan LDAP implementation. The first use of LDIF was in 
describing directory entries. Later, the format was expanded to 
allow representation of changes to directory entries. 
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Relationship to the application/directory MIME content-type: 


The application/directory MIME content-type [1] is a general 
framework and format for conveying directory information, and is 
independent of any particular directory service. The LDIF format is 
a simpler format which is perhaps easier to create, and may also be 
used, as noted, to describe a set of changes to be applied to a 
directory. 


The key words "MUST", "MUST NOT", "MAY", "SHOULD", and "SHOULD NOT" 
used in this document are to be interpreted as described in [7]. 


Definition of the LDAP Data Interchange Format 


The LDIF format is used to convey directory information, or a 
description of a set of changes made to directory entries. An LDIF 
file consists of a series of records separated by line separators. A 
record consists of a sequence of lines describing a directory entry, 
or a sequence of lines describing a set of changes to a directory 
entry. An LDIF file specifies a set of directory entries, or a set 
of changes to be applied to directory entries, but not both. 


There is a one-to-one correlation between LDAP operations that modify 
the directory (add, delete, modify, and modrdn), and the types of 
changerecords described below ("add", "delete", "modify", and 
"modrdn" or "moddn"). This correspondence is intentional, and 
permits a straightforward translation from LDIF changerecords to 
protocol operations. 


Formal Syntax Definition of LDIF 


The following definition uses the augmented Backus-Naur Form 
specified in RFC 2234 [2]. 


ldif-file = Idif-content / ldif-changes 

ldif-content = version-spec 1" (1"SEP ldif-attrval-record) 
ldi f-changes = version-spec 1*(1*SEP ldif-change-record) 
ldif-attrval-record = dn-spec SEP l"attrval-spec 
ldif-change-record = dn-spec SEP "control changerecord 
version-spec = "version:" FILL version-number 
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version-number 


dn-spec 


distinguishedName 


base64-distinguishedName 


rdn 


base64-rdn 


control 


ldap-oid 


attrval-spec 


value-spec 


url 


AttributeDescription 


AttributeType 


options 


Good 
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1*DIGIT 
; version-number MUST be "1" for the 
; LDIF format described in this document. 


"dn:" (FILL distinguishedName / 
":" FILL base64-distinguishedName) 


SAFE-STRING 
; a distinguished name, as defined in [3] 


BASE64-UTF8-STRING 
; a distinguishedName which has been base64 
; encoded (see note 10, below) 


SAFE-STRING 
; a relative distinguished name, defined as 
; <name-component> in [3] 


BASE64-UTF8-STRING 
; an rdn which has been base64 encoded (see 
; note 10, below) 


"control:" FILL ldap-oid ; controlType 
O*1(1*SPACE ("true" / "false")) ; criticality 
0"1 (value-spec) ; controlValue 
SEP 


; (See note 9, below) 


PEDIGIT 081(".," LAD EGET) 
; An LDAPOID, as defined in [4] 


AttributeDescription value-spec SEP 
Memo FILL 0%1(SAFE-STRING) / 
":" FILL (BASE64-STRING) / 
"<" FILL url) 
; See notes 7 and 8, below 
<a Uniform Resource Locator, 
as defined in [6]> 


; (See Note 6, below) 


AttributeType [";" options] 
; Definition taken from [4] 


ldap-oid / (ALPHA "(attr-type-chars)) 


option / (option ";" options) 
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option 


attr-type-chars 


opt-char 


changerecord 


change-add 
change-delete 


change-moddn 


change-modify 


mod-spec 


SPACE 


FILL 
SEP 


CR 


LF 


ALPHA 


DIGIT 


Good 
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l"opt-char 

ALPHA / DIGIT / "-" 

attr-type-chars 

"changetype:" FILL 

(change-add / change-delete / 
change-modify / change-moddn) 

"add" SEP l"attrval-spec 


"delete" SEP 


("modrdn" / "moddn") SEP 


"newrdn:" ( FILL rdn / 
":" FILL base64-rdn) SEP 
"deleteoldrdn:" FILL ("0" / "1") SEP 


01 ("newsuperior:" 
( FILL distinguishedName / 
":" FILL base64-distinguishedName) SEP) 


"modify" SEP *mod-spec 
("add:" / "delete:" / "replace:") 
FILL AttributeDescription SEP 
*attrval-spec 


" m SEP 


%x20 
; ASCII SP, space 


* SPACE 
(CR LF / LF) 


%x0D 
; ASCII CR, carriage return 


%x0A 
; ASCII LF, line feed 


%x41-5A / %x61-7A 
; A-Z / a-z 


%x30-39 
; 0-9 
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UTF8-1 = $x80-BF 
UTF8-2 = %xC0-DF UTF8-1 
UTF8-3 = %xE0-EF 2UTF8-1 
UTF8-4 = $xFO-F7 3UTF8-1 
UTF8-5 = $xF8-FB 4UTF8-1 
UTP 8-6 = $xFC-FD 5UTF8-1 
SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-7F 
; any value <= 127 decimal except NUL, LF, 
; and CR 
SAFE-INIT-CHAR = %x01-09 / %x0B-0C / %x0E-1F / 
%x21-39 / %x3B / %x3D-7F 
; any value <= 127 except NUL, LF, CR, 
; SPACE, colon (":", ASCII 58 decimal) 
; and less-than ("<" , ASCII 60 decimal) 
SAFE-STRING = [SAFE-INIT-CHAR *SAFE-CHAR] 
UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / 
UTF8-4 / UTF8-5 / UTF8-6 
UTF8-STRING = *UTF8—-CHAR 
BASE64-UTF8-STRING = BASE64-STRING 
; MUST be the base64 encoding of a 
; UTF8-STRING 
BASE64-CHAR = %x2B / %x2F / %x30-39 / %x3D / %x41-5A / 


BASE64-STRING 


%x61-7A 
; +, /, 0-9, z, A-Z, and a-z 
; as specified in [5] 


[* (BASE64-CHAR) | 


Notes on LDIF Syntax 


Good 


1) 


For the LDIF format described in this document, the version 
number MUST be "1". If the version number is absent, 
implementations MAY choose to interpret the contents as an 
older LDIF file format, supported by the University of 
Michigan ldap-3.3 implementation [8]. 
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2) Any non-empty line, including comment lines, in an LDIF file 
MAY be folded by inserting a line separator (SEP) and a SPACE. 
Folding MUST NOT occur before the first character of the line. 
In other words, folding a line into two lines, the first of 
which is empty, is not permitted. Any line that begins with a 
single space MUST be treated as a continuation of the previous 
(non-empty) line. When joining folded lines, exactly one space 
character at the beginning of each continued line must be 
discarded. Implementations SHOULD NOT fold lines in the middle 
of a multi-byte UTF-8 character. 


3) Any line that begins with a pound-sign ("#", ASCII 35) isa 
comment line, and MUST be ignored when parsing an LDIF file. 


4) Any dn or rdn that contains characters other than those 
defined as "SAFE-UTF8-CHAR", or begins with a character other 
than those defined as "SAFE-INIT-UTF8-CHAR", above, MUST be 
base-64 encoded. Other values MAY be base-64 encoded. Any 
value that contains characters other than those defined as 
"SAFE-CHAR", or begins with a character other than those 
defined as "SAFE-INIT-CHAR", above, MUST be base-64 encoded. 
Other values MAY be base-64 encoded. 


5) When a zero-length attribute value is to be included directly 
in an LDIF file, it MUST be represented as 


AttributeDescription ":" FILL SEP. For example, "seeAlso:" 
followed by a newline represents a zero-length "seeAlso" 
attribute value. It is also permissible for the value 


referred to by a URL to be of zero length. 


6) When a URL is specified in an attrval-spec, the following 
conventions apply: 


a) Implementations SHOULD support the file:// URL format. The 
contents of the referenced file are to be included verbatim 
in the interpreted output of the LDIF file. 

b) Implementations MAY support other URL formats. The 
semantics associated with each supported URL will be 
documented in an associated Applicability Statement. 


7) Distinguished names, relative distinguished names, and 
attribute values of DirectoryString syntax MUST be valid UTF-8 
strings. Implementations that read LDIF MAY interpret files 
in which these entities are stored in some other character set 
encoding, but implementations MUST NOT generate LDIF content 
which does not contain valid UTF-8 data. 
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8) Values or distinguished names that end with SPACE SHOULD be 
base-64 encoded. 


9) When controls are included in an LDIF file, implementations 
MAY choose to ignore some or all of them. This may be 
necessary if the changes described in the LDIF file are being 
sent on an LDAPv2 connection (LDAPv2 does not support 
controls), or the particular controls are not supported by the 
remote server. If the criticality of a control is "true", then 
the implementation MUST either include the control, or MUST 
NOT send the operation to a remote server. 


10) When an attrval-spec, distinguishedName, or rdn is base64- 
encoded, the encoding rules specified in [5] are used with the 
following exceptions: a) The requirement that base64 output 
streams must be represented as lines of no more than 76 
characters is removed. Lines in LDIF files may only be folded 
according to the folding rules described in note 2, above. b) 
Base64 strings in [5] may contain characters other than those 
defined in BASE64-CHAR, and are ignored. LDIF does not permit 
any extraneous characters, other than those used for line 
folding. 


Examples of LDAP Data Interchange Format 
Example 1: An simple LDAP file with two entries 


version: 1 

dn: cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com 
objectclass: top 

objectclass: person 

objectclass: organizationalPerson 
cn: Barbara Jensen 

cn: Barbara J Jensen 

cn: Babs Jensen 

sn: Jensen 

uid: bjensen 

telephonenumber: +1 408 555 1212 
description: A big sailing fan. 


dn: cn=Bjorn Jensen, ou=Accounting, dc=airius, dc=com 
objectclass: top 

objectclass: person 

objectclass: organizationalPerson 

cn: Bjorn Jensen 

sn: Jensen 

telephonenumber: +1 408 555 1212 
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Example 2: A file containing an entry with a folded attribute value 


version: 1 

dn:cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com 
objectclass:top 

objectclass:person 

objectclass:organizationalPerson 

cn:Barbara Jensen 

cn:Barbara J Jensen 

cn:Babs Jensen 

sn:Jensen 

uid:bjensen 

telephonenumber:+1 408 555 1212 

description:Babs is a big sailing fan, and travels extensively in sea 
rch of perfect sailing conditions. 

title:Product Manager, Rod and Reel Division 


Example 3: A file containing a base-64-encoded value 


version: 1 

dn: cn=Gern Jensen, ou=Product Testing, dc=airius, dc=com 

objectclass: top 

objectclass: person 

objectclass: organizationalPerson 

cn: Gern Jensen 

cn: Gern O Jensen 

sn: Jensen 

uid: gernj 

telephonenumber: +1 408 555 1212 

description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaG1zIHZhbHV1 
TG1zIGJhc2vUtnNnjOt ZW5 jb2R1ZCBiZWNhdXN1IG1LOIGhhcyBhIGNvbnRyb2wgY2hhcmF jdG 
VyIGluIGLOIChhIENSKS4NICBCeSBOaGUgd2F5LCB5b3Ugc2hvdWxkIHJLYWxseSBnZxXOg 
b3V0IGlvcmUu 


Example 4: A file containing an entries with UTF-8-encoded attribute 
values, including language tags. Comments indicate the contents 
of UTF-8-encoded attributes and distinguished names. 


version: 1 

dn:: b3U95Za25gWt6YO0oLG890WlyaXVz 

# dn:: ou=<JapaneseOU>, o=Airius 

objectclass: top 

objectclass: organizationalUnit 

ou:: 5Za25gWt6YO00o 

# ou:: <JapaneseOU> 

ou; lang-ja:: 5Za25qwt6YOo 

# ou;lang-ja:: <JapaneseOU> 

ou; lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2 
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# ou;lang-ja:: <JapaneseOU_in_phonetic_representation> 
ou;lang-en: Sales 
description: Japanese office 


dn:: dWlkPXJvZ2FzYXdhcmEsb3U95Za25gWt6YOoLG890W1lyaXVz 
4 dn:: uid=<uid>, ou=<JapaneseOU>, o=Airius 
userpassword: (SHA)O3HSvlMusyL4kTjP4HKI5uxuNoM- 
objectclass: top 

objectclass: person 

objectclass: organizationalPerson 

objectclass: inetorgPerson 

uid: rogasawara 

mail: rogasawara@airius.co.jp 

givenname; lang-ja:: 440t440J440L4408 

4 givenname;lang-ja:: <JapaneseGivenname> 

sn; lang-ja:: 5bCP56yg5Y6f 

4 sn;lang-ja:: <JapaneseSn> 

Gn: lang-ja:: 5bCP56yg5Y6£IOODreODieODitODvA-< 

4 cn;lang-ja:: <JapaneseCn> 

title;lang-ja:: 5Za25qwt6YOolOmDqOmVt w== 

# title;lang-ja:: <JapaneseTitle> 
preferredlanguage: ja 

givenname:: 440t440J440L4408 

# givenname:: <JapaneseGivenname> 

sn:: 5bCP56yg5Y6f 

# sn:: <JapaneseSn> 

cn:: 5bCP56yg5Y6fIOODreODieODitODvA-<- 

# cn:: <JapaneseCn> 

title:: 5Za25qwt 6YOolOmDqOmVtw== 

# title:: <JapaneseTitle> 

givenname; lang-ja;phonetic:: 44KN44Gp44Gr4408 

# givenname; lang-ja;phonetic:: 
<JapaneseGivenname_in_phonetic_representation_kana> 
sn; lang-ja;phonetic:: 44GK44GM44GV44KP44KJ 


4 sn;lang-ja;phonetic:: <JapaneseSn in phonetic representation kana> 
cn; lang-ja;jphonetic:: 44GK44GM44GV44KP44KJIOOC jeOBgeOBgtODvA<< 
4 cn;lang-ja;phonetic:: <JapaneseCn in phonetic representation kana> 


title; lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2 IOOBtuOBoe0Cht0Bhg<-< 
# title;lang-ja;phonetic:: 

# <JapaneseTitle in phonetic representation kana> 

givenname; lang-en: Rodney 

sn; lang-en: Ogasawara 

Gn: lang-en: Rodney Ogasawara 

title; lang-en: Sales, Director 


Good Standards Track [Page 9] 


RFC 2849 LDAP Data Interchange Format June 2000 


Example 5: A file containing a reference to an external file 


version: 1 

dn: cn=Horatio Jensen, ou=Product Testing, dc=airius, dc=com 
objectclass: top 

objectclass: person 

objectclass: organizationalPerson 

cn: Horatio Jensen 


cn: Horatio N Jensen 

sn: Jensen 

uid: hjensen 

telephonenumber: +1 408 555 1212 

jpegphoto:< file:///usr/local/directory/photos/hjensen. jpg 


Example 6: A file containing a series of change records and comments 


version: 1 

# Add a new entry 

dn: cn=Fiona Jensen, ou=Marketing, dc=airius, dc=com 
changetype: add 

objectclass: top 

objectclass: person 

objectclass: organizationalPerson 

cn: Fiona Jensen 

sn: Jensen 

uid: fiona 

telephonenumber: +1 408 555 1212 

jpegphoto:< file:///usr/local/directory/photos/fiona. jpg 


# Delete an existing entry 
dn: cn=Robert Jensen, ou=Marketing, dc=airius, dc=com 
changetype: delete 


# Modify an entry’s relative distinguished name 

dn: cn=Paul Jensen, ou=Product Development, dc=airius, dc=com 
changetype: modrdn 

newrdn: cn=Paula Jensen 

deleteoldrdn: 1 


# Rename an entry and move all of its children to a new location in 
# the directory tree (only implemented by LDAPv3 servers). 

dn: ou=PD Accountants, ou=Product Development, dc=airius, dc=com 
changetype: modrdn 

newrdn: ou=Product Development Accountants 

deleteoldrdn: 0 

newsuperior: ou=Accounting, dc=airius, dc=com 
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Modify an entry: add an additional value to the postaladdress 
attribute, completely delete the description attribute, replace 

the telephonenumber attribute with two values, and delete a specific 
value from the facsimiletelephonenumber attribute 

dn: cn=Paula Jensen, ou=Product Development, dc=airius, dc=com 
changetype: modify 

add: postaladdress 

postaladdress: 123 Anystreet $ Sunnyvale, CA $ 94086 


Se SE SR He 


delete: description 

replace: telephonenumber 
telephonenumber: +1 408 555 1234 
telephonenumber: +1 408 555 5678 


delete: facsimiletelephonenumber 
facsimiletelephonenumber: +1 408 555 9876 


Modify an entry: replace the postaladdress attribute with an empty 
set of values (which will cause the attribute to be removed), and 
delete the entire description attribute. Note that the first will 
always succeed, while the second will only succeed if at least 

one value for the description attribute is present. 

dn: cn=Ingrid Jensen, ou=Product Support, dc=airius, dc=com 
changetype: modify 

replace: postaladdress 


SE SR dk dk SE 


delete: description 


Example 7: An LDIF file containing a change record with a control 
version: 1 

# Delete an entry. The operation will attach the LDAPv3 

# Tree Delete Control defined in [9]. The criticality 

# field is "true" and the controlValue field is 

# absent, as required by [9]. 

dn: ou=Product Development, dc=airius, dc=com 

control: 1.2.840.113556.1.4.805 true 

changetype: delete 
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Security Considerations 


Given typical directory applications, an LDIF file is likely to 
contain sensitive personal data. Appropriate measures should be 
taken to protect the privacy of those persons whose data is contained 
in an LDIF file. 


Since ":<" directives can cause external content to be included when 
processing an LDIF file, one should be cautious of accepting LDIF 
files from external sources. A "trojan" LDIF file could name a file 
with sensitive contents and cause it to be included in a directory 
entry, which a hostile entity could read via LDAP. 


LDIF does not provide any method for carrying authentication 
information with an LDIF file. Users of LDIF files must take care to 
verify the integrity of an LDIF file received from an external 
source. 


Acknowledgments 


The LDAP Interchange Format was developed as part of the University 
of Michigan LDAP reference implementation, and was developed by Tim 
Howes, Mark Smith, and Gordon Good. It is based in part upon work 
supported by the National Science Foundation under Grant No. NCR- 
9416667. 


Members of the IETF LDAP Extensions Working group provided many 
helpful suggestions. In particular, Hallvard B. Furuseth of the 
University of Oslo made many significant contributions to this 
document, including a thorough review and rewrite of the BNF. 


References 


[1] Howes, T. and M. Smith, "A MIME Content-Type for Directory 
Information", RFC 2425, September 1998. 


[2] Crocker, D., and P. Overell, "Augmented BNF for Syntax 
Specifications: ABNF", RFC 2234, November 1997. 


[3] Wahl, M., Kille, S. and T. Howes, "A String Representation of 
Distinguished Names", RFC 2253, December 1997. 


[4] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access 
Protocol (v3)", RFC 2251, July 1997. 


[5] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 
Extensions (MIME) Part One: Format of Internet Message Bodies", 
RFC 2045, November 1996. 


Good Standards Track [Page 12] 


RFC 2849 LDAP Data Interchange Format June 2000 


[6] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform 
Resource Locators (URL)", RFC 1738, December 1994. 


[7] Bradner, S., "Key Words for use in RFCs to Indicate Requirement 
Levels", BCP 14, RFC 2119, March 1997. 


[8] The SLAPD and SLURPD Administrators Guide. University of 
Michigan, April 1996.  <URL: 
http://www.umich.edu/"dirsvcs/ldap/doc/guides/slapd/toc.html> 


[9] M. P. Armijo, "Tree Delete Control", Work in Progress. 
Author’s Address 

Gordon Good 

iPlanet e-commerce Solutions 

150 Network Circle 

Mailstop USCA17-201 

Santa Clara, CA 95054, USA 


Phone: +1 408 276 4351 
EMail: ggood@netscape.com 


Good Standards Track [Page 13] 


RFC 2849 LDAP Data Interchange Format June 2000 


Full Copyright Statement 
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This document and translations of it may be copied and furnished to 
others, and derivative works that comment on or otherwise explain it 
or assist in its implementation may be prepared, copied, published 
and distributed, in whole or in part, without restriction of any 
kind, provided that the above copyright notice and this paragraph are 
included on all such copies and derivative works. However, this 
document itself may not be modified in any way, such as by removing 
the copyright notice or references to the Internet Society or other 
Internet organizations, except as needed for the purpose of 
developing Internet standards in which case the procedures for 
copyrights defined in the Internet Standards process must be 
followed, or as reguired to translate it into languages other than 
English. 


The limited permissions granted above are perpetual and will not be 
revoked by the Internet Society or its successors or assigns. 


This document and the information contained herein is provided on an 
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 
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